home *** CD-ROM | disk | FTP | other *** search
/ Aminet 1 (Walnut Creek) / Aminet - June 1993 [Walnut Creek].iso / aminet / util / libs / cwrlib31.lha / cwrite.doc < prev    next >
Text File  |  1992-07-22  |  9KB  |  293 lines
  1. TABLE OF CONTENTS
  2.  
  3. cwrite.library/CWrite
  4. cwrite.library/CWriteAlloc
  5. cwrite.library/CWriteCloseWindow
  6. cwrite.library/CWriteCursorType
  7. cwrite.library/CWriteFree
  8. cwrite.library/CWriteInit
  9. cwrite.library/CWriteOpenWindow
  10. cwrite.library/CWriteSetColors
  11. cwrite.library/CWrite                                   cwrite.library/CWrite
  12.  
  13.     NAME
  14.         CWrite -- Writes bytes containing CSI sequences to a window.
  15.  
  16.     SYNOPSIS
  17.     CWrite( CwrData, buffer, length )
  18.         A0     A1     D0
  19.  
  20.     VOID CWrite(struct CwrData *, UBYTE *, LONG);
  21.  
  22.     FUNCTION
  23.     CWrite() writes bytes of data to the window contained in the CwrData
  24.     structure. 'length' indicates the length of data to be written;
  25.     'buffer' is a pointer to the buffer to be written.
  26.  
  27.     The data written to the window may contain ANSI escape sequences
  28.     as used on standard PC-type computers.
  29.     I.e. 0x1b[1;31;40m but not 0x9b1;31;40m as normally used on the
  30.     Amiga computer.
  31.     This means, that characters not normally visible when written to the
  32.     console.device will be visible when written with this function.
  33.     An example could be characters within the ascii code range 128 to 160
  34.     There are, however, some control codes that are not written to the
  35.     screen; read the README file for further documentation on that.
  36.  
  37.     Be sure to use CWriteInit() before attempting to use this function.
  38.  
  39.     INPUTS
  40.     CwrData - pointer to an initialized CwrData structure
  41.     buffer - pointer to the buffer
  42.     length - integer
  43.  
  44.     RESULTS
  45.     None.
  46.  
  47.     SEE ALSO
  48.     CWriteAlloc(), CWriteCursorType(), CWriteFree(), CWriteInit()
  49.  
  50. cwrite.library/CWriteAlloc                         cwrite.library/CWriteAlloc
  51.  
  52.     NAME
  53.     CWriteAlloc -- Allocates memory for the CWrite functions.
  54.  
  55.     SYNOPSIS
  56.     Cdata = CWriteAlloc()
  57.     D0
  58.  
  59.     struct CwrData *CWriteAlloc(void)
  60.  
  61.     FUNCTION
  62.     CWriteAlloc() is used to allocate memory for the CWrite functions.
  63.     Never deallocate memory by yourself, that is allocated by this
  64.     function, use CWriteFree().
  65.     It is advisable not to allocate memory by yourself, as the data
  66.     structure might change in size in future releases.
  67.     Before using this pointer to the CWrite functions, you must first
  68.     initialize it using the CWriteInit() library function.
  69.  
  70.     RESULTS
  71.     Cdata - pointer to a CwrData structure
  72.     error - if zero, the memory needed for the CwrData structure could
  73.         not be allocated.
  74.  
  75.     SEE ALSO
  76.     CWriteFree(), CWriteInit()
  77.  
  78. cwrite.library/CWriteCloseWindow             cwrite.library/CWriteCloseWindow
  79.  
  80.     NAME
  81.     CWriteCloseWindow -- Closes a window opened by CWriteOpenWindow.
  82.  
  83.     SYNOPSIS
  84.     CWriteCloseWindow( window )
  85.                A0
  86.  
  87.     VOID CWriteCloseWindow( struct Window * );
  88.  
  89.     FUNCTION
  90.     CWriteCloseWindow() closes both the window and the screen contained
  91.     in the window structure.
  92.     Be sure that you don't use this function on a window opened on the
  93.     workbench screen, as it will try to close this screen too.
  94.  
  95.     INPUTS
  96.     window - pointer to a Window structure
  97.  
  98.     RESULTS
  99.     None.
  100.  
  101.     SEE ALSO
  102.     CWriteOpenWindow()
  103.  
  104. cwrite.library/CWriteCursorType               cwrite.library/CWriteCursorType
  105.  
  106.     NAME
  107.     CWriteCursorType -- Changes the cursortype in a CwrData structure.
  108.  
  109.     SYNOPSIS
  110.     CWriteCursorType( CwrData, type )
  111.               A0       D0
  112.  
  113.     VOID CWriteCursorType(struct CwrData *, UBYTE);
  114.  
  115.     FUNCTION
  116.     CWriteCursorType() changes the cursortype in a CwrData structure to
  117.     another kind of cursortype.
  118.     The initial cursortype, as of after using the CWriteInit function,
  119.     is allways of type CURSORTYPE_NONE.
  120.     Currently supported are two different cursortypes, or no cursor at
  121.     all.
  122.  
  123.     The CURSORTYPE_FAST cursortype has been made to be the fastest
  124.     available, but may also cause troubles, if your program have more
  125.     than one window opened on the current screen, as it writes directly
  126.     into the first bitplane of the rastport, and will therefore also
  127.     write into other windows opened on the screen. This cursortype will
  128.     allways be 8 pixels wide, without taking care of the X-size of the
  129.     font. It will, however, follow the size in the Y direction.
  130.     Do not use this cursortype if you possibly can avoid it!
  131.  
  132.     The CURSORTYPE_SLOW cursortype uses the intuition.library functions
  133.     SetDrMode() and RectFill() to write the cursor, and is ofcourse
  134.     much slower than the CURSORTYPE_FAST. - It shouldn't, however, cause
  135.     any troubles on a screen with more than one window opened. This
  136.     cursortype will allways follow the font size, no matter how high or
  137.     wide that size might be.
  138.     The routines for this cursortype has been heavily improved, and
  139.     it is almost as fast as the CURSORTYPE_FAST cursortype routines.
  140.     This is the recommended cursortype. Please avoid the CURSORTYPE_FAST
  141.     cursortype if you can.
  142.  
  143.     The CURSORTYPE_NONE turns the cursor completely off.
  144.  
  145.     The CURSORTYPE_GHOSTED will 'ghost' the cursor, just like the OS2
  146.     console.device.
  147.     This cursortype will use the same routines as the CURSORTYPE_SLOW,
  148.     and is using the SetDrMode() and RectFill() routines from the
  149.     intuition.library as well as CURSORTYPE_SLOW does.
  150.     Use this cursortype, if your window goes in 'INACTIVEWINDOW' mode.
  151.  
  152.     Other values will have the same effect as CURSORTYPE_NONE.
  153.  
  154.     INPUTS
  155.     CwrData - pointer to an initialized CwrData structure
  156.     type - byte value
  157.  
  158.     RESULTS
  159.     None.
  160.  
  161.     SEE ALSO
  162.     CWriteInit()
  163.  
  164. cwrite.library/CWriteFree                           cwrite.library/CWriteFree
  165.  
  166.     NAME
  167.     CWriteFree - Frees memory allocated by the CWriteAlloc function.
  168.  
  169.     SYNOPSIS
  170.     CWriteFree( Cdata )
  171.             A0
  172.  
  173.     VOID CWriteFree( struct CwrData * );
  174.  
  175.     FUNCTION
  176.     CWriteFree() frees memory allocated by the CWriteAlloc() function.
  177.  
  178.     RESULTS
  179.     None.
  180.  
  181.     SEE ALSO
  182.     CWriteAlloc()
  183.  
  184. cwrite.library/CWriteInit                           cwrite.library/CWriteInit
  185.  
  186.     NAME
  187.     CWriteInit -- Initializes a structure for use in CWrite.
  188.  
  189.     SYNOPSIS
  190.     CWriteInit( CwrData, window )
  191.             A0         A1
  192.  
  193.     VOID CWriteInit(struct CwrData *, struct Window *);
  194.  
  195.     FUNCTION
  196.     CWriteInit() initializes a CwrData structure to use by the CWrite
  197.     and CWriteCursorType functions.
  198.     It MUST be called before attempting to use CWrite()!
  199.     Be sure, that the memory for the CwrData structure are allocated
  200.     properly, by using the CWriteAlloc() routine, or else you might get
  201.     very weird results.
  202.     
  203.     The window MUST be borderless, as the very fast scrolling routines
  204.     in the library will not work properly if it isn't.
  205.  
  206.     INPUTS
  207.     CwrData - pointer to a CwrData structure
  208.     window - pointer to a window
  209.  
  210.     RESULTS
  211.     None.
  212.  
  213.     SEE ALSO
  214.     CWrite(), CWriteCursorType(), CWriteFree(), CWriteOpenWindow()
  215.  
  216. cwrite.library/CWriteOpenWindow               cwrite.library/CWriteOpenWindow
  217.  
  218.     NAME
  219.     CWriteOpenWindow -- Opens a screen and a borderless window.
  220.  
  221.     SYNOPSIS
  222.     window = CWriteOpenWindow(title, width, height, planes, interlace)
  223.     D0              A0     D0    D1    D2    D3
  224.  
  225.     struct Window *CWriteOpenWindow( UBYTE *, int, int, int, BOOL );
  226.  
  227.     FUNCTION
  228.     CWriteOpenWindow() opens a screen with title 'title', width 'width',
  229.     height 'height' in 'planes' bitplanes. If the 'interlace' is non-zero
  230.     the screen will be opened in interlace mode.
  231.     If the opening of the screen is succesfull, the function will open
  232.     a window slightly smaller than the screen, to make sure that the
  233.     window starts right below the title bar of the screen.
  234.     The IDCMPFlags of the window, are at the time being RAWKEY and
  235.     MENUPICK, but they may be altered using the intuition function
  236.     ModifyIDCMP().
  237.     The window opened will always be borderless, as all windows should
  238.     be when using this library.
  239.     After successful opening of the screen and window, the library will
  240.     automatically call the CWriteSetColors() function, to make sure that
  241.     the correct ANSI colors will be used.
  242.     If you decide not to use the library routine CWriteOpenWindow(),
  243.     you must take care of two things:
  244.        1.    The window may _NOT_ go behind the titlebar of the screen.
  245.         - To make sure of this, you can define the TopEdge member of
  246.         the newwindow structure to start at a value of 10. - This is
  247.         the offset used in the CWriteOpenWindow() function.
  248.        2.    The window _MUST_ be borderless.
  249.         - The very fast scroll routines in the library will not work
  250.         properly if it isn't.
  251.  
  252.     INPUTS
  253.     title - pointer to a nullterminated string
  254.     width - integer
  255.     height - integer
  256.     planes - integer
  257.     interlace - BOOL value of either zero or one
  258.  
  259.     RESULTS
  260.     window - pointer to the opened Window.
  261.     error -  if zero, the window or screen could not be opened.
  262.  
  263.     SEE ALSO
  264.     CWriteCloseWindow(), CWriteSetColors()
  265.  
  266. cwrite.library/CWriteSetColors                 cwrite.library/CWriteSetColors
  267.  
  268.     NAME
  269.     CWriteSetColors -- Changes colors to standard ANSI colors.
  270.  
  271.     SYNOPSIS
  272.     CWriteSetColors( window )
  273.              A0
  274.  
  275.     VOID CWriteSetColors(struct Window *);
  276.  
  277.     FUNCTION
  278.     CWriteSetColors() sets the colors in the viewport to the standard
  279.     ANSI colors used by this library.
  280.     According to how many bitplanes you have on the current screen,
  281.     this function will change all colors available to the standard
  282.     ANSI colors, as used by this library.
  283.  
  284.     INPUTS
  285.     window - pointer to a Window structure
  286.  
  287.     RESULTS
  288.     None.
  289.  
  290.     SEE ALSO
  291.     CWriteOpenWindow()
  292.  
  293.